Návod k editaci JSON šablony — Tabulková sestava

Tento návod je určen pro úpravu JSON šablon tabulkových sestav (přehledy dokladů, účetní výpisy, ceníky apod.) ve VS Code s live preview.

Obsah:

• Jak to funguje · Editace ve VS Code · Struktura šablony
• 1. Nastavení sestavy · 2. Záhlaví · 3. Sekce · 4. Sloupce
• 5. Počítané sloupce · 6. Průběžný součet · 7. Template · 8. Viditelnost
• 9. Potlačení opakování · 10. Skupiny · 11. Součty · 11b. Víceřádkové patičky
• 11c. Podpole · 11d. Mezera před totalem · 11e. Markdown · 11f. Bloky pod tabulkou
• 12. Lookup tabulky · 12b. Aliasy · 13. Dynamické labely · 14. Stránkování
• 15. Lokalizace · 16. ShowProgress · 17. Generování z FRX
• Příklady z praxe · Řešení problémů · Znakové jednotky šířek · Doporučené šířky v mm · Časté úpravy

Jak to funguje

┌───────────────────────────────────────────────────────────┐
│  XML data         +    JSON šablona    →    HTML / PDF    │
│  (z aplikace)          (vaše úpravy)        (výstup)      │
└───────────────────────────────────────────────────────────┘

XML data — připraví aplikace (FoxPro). Obsahují reálná data: čísla dokladů, názvy, ceny, datumy.

JSON šablona — tu upravujete vy. Říká rendereru, jak data zobrazit: které sloupce, jaké formáty, skupiny, součty.

Výstup — HTML (náhled v prohlížeči), PDF (tisk), XLSX (Excel).

Editace ve VS Code

Editaci spustíte z aplikace. Otevře se VS Code s JSON souborem a v prohlížeči se zobrazí HTML náhled.

Základní workflow

1. Otevřete editaci z aplikace (tlačítko "Upravit šablonu")
2. VS Code se otevře se JSON souborem, v prohlížeči se zobrazí náhled
3. Upravte JSON šablonu ve VS Code
4. Uložte (Ctrl+S) — náhled v prohlížeči se automaticky obnoví za ~2 sekundy
5. Zkontrolujte výsledek v prohlížeči
6. Opakujte kroky 3–5

VS Code nápověda (IntelliSense)

• Ctrl+Space — zobrazí dostupné vlastnosti (co můžete napsat na tomto místě)
• Najetí myší na vlastnost — zobrazí popis
• Schéma automaticky kontroluje správnost — červené podtržení = chyba

Pravidla JSON

Pozor: JSON soubor musí být validní JSON. Nejčastější chyby:

• Čárka za poslední položkou v {} nebo [] — to v JSON nelze
• Chybějící uvozovky: label: Název → správně "label": "Název"
• Chybějící čárka mezi položkami

Tip: VS Code červeně podtrhne chybu. Ctrl+Z vrátí zpět poslední změnu.

Struktura JSON šablony

Šablona má tyto hlavní části:

{
  "renderer":   "table",      ← typ šablony (volitelné, pro jednoznačnou identifikaci)
  "aliases":    { ... },      ← zkratky pro dlouhé XML cesty (volitelné)
  "report":     { ... },      ← nastavení celé sestavy
  "header":     { ... },      ← záhlaví (firma, filtr, logo)
  "footer":     { ... },      ← zápatí
  "pageHeader": { ... },      ← záhlaví stránky (opakuje se)
  "pageFooter": { ... },      ← zápatí stránky (opakuje se)
  "i18n":       { ... },      ← překlady textů
  "sections":   [ ... ]       ← sekce s daty (tabulky)
}

1. Nastavení sestavy (report)

{
  "report": {
    "title": "Přehled dokladů",
    "culture": "cs-CZ",
    "orientation": "landscape",
    "pageSize": "A4"
  }
}

Nejčastější vlastnosti

Speciální vlastnosti

Styly okrajů (detailBorders)

2. Záhlaví sestavy (header)

{
  "header": {
    "company": "EFES spol. s r.o.\nNeklanova 18\n128 00 Praha 2",
    "filter": "Období: leden 2026",
    "logoFile": "C:\\data\\logo.jpg"
  }
}

Logo může být i dynamické: "logoFile": "{header.logoFile}" — cesta se načte z XML dat.

Adresa firmy z XML — parametr.adresa1 a parametr.adresa2

Pokud XML data obsahují element parametr s atributy adresa1 a/nebo adresa2, renderer je automaticky použije pro adresu vlevo nahoře — bez ohledu na header.company v JSON:

• adresa1 — první řádek, tučně (HTML: 10 pt, PDF: 9 pt)
• adresa2 — zbytek adresy, víceřádkový (HTML: 9 pt, PDF: 8 pt), rozdělený po řádcích (\n)

loBuilder.Push("parametr")
loBuilder.AddAttribute("adresa1", "EFES spol. s r.o.")
loBuilder.AddAttribute("adresa2", "Neklanova 18" + CHR(10) + "128 00 Praha 2")
loBuilder.Pop()

Výsledek v záhlaví (vlevo nahoře):

EFES spol. s r.o.   ← tučně
Neklanova 18
128 00 Praha 2

Pokud parametr element v XML chybí nebo nemá atributy adresa1/adresa2, použije se header.company jako dříve.

3. Sekce (sections)

Sekce jsou nezávislé části sestavy — každá má vlastní sloupce, skupiny a součty.

{
  "sections": [
    {
      "element": "doklady",
      "label": "Přehled dokladů",
      "columns": { ... },
      "groups": [ ... ],
      "sumExpressions": [ ... ]
    },
    {
      "element": "rekapitulace",
      "label": "Rekapitulace DPH",
      "columns": { ... }
    }
  ]
}

Rozvaha — více sekcí se stejným elementem

Typický případ: XML obsahuje jednu plochou tabulku s aktivy i pasivy rozlišenými atributem lk1. Pomocí "where" vytvoříte dvě sekce ze stejných dat:

{
  "sections": [
    {
      "element": "data",
      "label": "AKTIVA",
      "where": "lk1=A",
      "columns": {
        "text":   { "label": "Položka" },
        "castka": { "label": "Částka", "align": "right", "format": "N2" }
      },
      "sumExpressions": [{ "field": "castka", "expr": "SUM(castka)", "format": "N2" }],
      "sumLabel": "Aktiva celkem"
    },
    {
      "element": "data",
      "label": "PASIVA",
      "where": "lk1=P",
      "columns": {
        "text":   { "label": "Položka" },
        "castka": { "label": "Částka", "align": "right", "format": "N2" }
      },
      "sumExpressions": [{ "field": "castka", "expr": "SUM(castka)", "format": "N2" }],
      "sumLabel": "Pasiva celkem"
    }
  ]
}

Syntaxe where (stejná jako u sumRows):

Pořadí sekcí se stejným element: Výstup následuje pořadí JSON (ne pořadí v XML). Sekce AKTIVA bude tedy vždy před PASIVA bez ohledu na pořadí řádků v XML.

4. Sloupce (columns)

Sloupce se definují jako objekt — klíč je název XML atributu, hodnota je nastavení:

{
  "columns": {
    "cislo":  { "label": "Číslo",    "align": "center", "width": "60px" },
    "nazev":  { "label": "Název",    "align": "left" },
    "datum":  { "label": "Datum",    "align": "center", "format": "dd.MM.yyyy" },
    "cena":   { "label": "Částka",   "align": "right",  "format": "N2" },
    "pozn":   { "hide": true }
  }
}

Základní vlastnosti sloupce

Formáty (format)

Zkrácení textu — . na konci přidá trojtečku (…), w ořízne na celé slovo.

Formáty v praxi (XML → JSON → výstup)

Číslo s 2 desetinnými místy:

Datum:

Záporná čísla červeně:

Pokročilé vlastnosti sloupce

5. Počítané sloupce (expr)

Sloupec může místo XML hodnoty zobrazit výsledek výpočtu:

{
  "celkem": {
    "label": "Celkem",
    "expr": "cena * pocet",
    "format": "N2",
    "round": 2,
    "align": "right"
  },
  "s_dph": {
    "label": "S DPH",
    "expr": "cena * pocet * 1.21",
    "format": "N2",
    "round": 2,
    "align": "right"
  }
}

Ve výrazech můžete použít:

• Názvy polí z XML: cena, pocet, sleva
• Čísla: 1.21, 100
• Operátory: +, -, *, /
• Závorky: (cena - sleva) * pocet
• Tečkovou notaci: hlavicky.kurz (hodnota z jiného XML elementu)

6. Průběžný součet (running)

Sloupec s running: true zobrazuje narůstající součet:

{
  "zustatek": {
    "label": "Zůstatek",
    "expr": "prijem - vydaj",
    "running": true,
    "resetAt": "ucet",
    "format": "N2",
    "align": "right"
  }
}

resetAt = název skupiny, při jejíž změně se zůstatek vynuluje.

7. Template sloupce

Sloučí hodnoty z více polí do jednoho sloupce:

{
  "adresa": {
    "label": "Adresa",
    "template": "{ulice}, {psc} {mesto}"
  },
  "cena_mena": {
    "label": "Cena",
    "template": "{cena:N2} {parametry.mena}"
  }
}

V šabloně:

• {pole} — vloží hodnotu pole
• {pole:N2} — formátovaná hodnota (2 des. místa)
• {pole:50} — zkrácení na 50 znaků (tvrdé oříznutí)
• {pole:50.} — oříznutí + trojtečka … (celkem ≤ 50 znaků)
• {pole:50w} — oříznutí na poslední celé slovo ≤ 50 znaků
• {pole:50w.} — celé slovo + trojtečka
• {element.pole} — hodnota z jiného XML elementu (tečková notace)

Víceřádkové buňky (\n v template)

Znak \n v šabloně vytvoří víceřádkovou buňku:

{
  "adresa": {
    "label": "Adresa",
    "template": "{ulice}\n{psc} {mesto}"
  }
}

Výsledek:

┌──────────────────┐
│ Hlavní 15        │
│ 110 00 Praha     │
└──────────────────┘

• HTML — \n se převede na <br>
• PDF — každý řádek jako samostatný odstavec v buňce
• XLSX — buňka s WrapText, \n jako zalomení řádku

8. Podmíněná viditelnost (visibleWhen)

Sloupec nebo celá sekce se zobrazí jen pokud je podmínka splněna:

{
  "cena_eur": {
    "label": "Cena EUR",
    "format": "N2",
    "visibleWhen": "header.je_cizi_mena"
  },
  "kurz": {
    "label": "Kurz",
    "format": "N3",
    "visibleWhen": "header.kurz>1"
  }
}

Podporované podmínky

• Za "nemá hodnotu" se počítá: prázdný řetězec, "0", "0,00", "0.00"
• Číselné operátory (>, >=, <, <=) porovnávají jako desetinná čísla
• Tečková notace funguje: "header.kurz>1", "objednavka.hlavicka.mena=EUR"

Funguje na:

• sloupcích — visibleWhen na sloupci
• sekcích — visibleWhen na sekci

9. Potlačení opakovaných hodnot (suppressRepeat)

{
  "faktura": {
    "label": "Faktura",
    "suppressRepeat": true
  }
}

Hodnota "FV001" se zobrazí jen jednou. Při změně skupiny se tracker resetuje.

Poznámka: V XLSX výstupu se suppressRepeat automaticky ignoruje — Excel uživatel potřebuje kompletní hodnoty pro filtrování, řazení a vzorce.

9b. Výběr a pořadí sloupců (printColumns)

V columns definujete všechny dostupné sloupce. Property printColumns na sekci pak za běhu vybere, které z nich se vytisknou a v jakém pořadí.

{
  "sections": [{
    "element": "doklady",
    "printColumns": "rada,doklad,castka,text",
    "columns": {
      "rada": { "label": "Řada" },
      "doklad": { "label": "Doklad" },
      "ucet_md": { "label": "MD" },
      "ucet_d": { "label": "D" },
      "castka": { "label": "Částka", "format": "N2" },
      "text": { "label": "Text" },
      "organizace": { "label": "Organizace" }
    }
  }]
}

→ Vytisknou se jen 4 sloupce: rada, doklad, castka, text.

Dynamický výběr z XML: Pomocí {element.field} se seznam sloupců načte z XML dat:

"printColumns": "{parametry.sloupce}"

Ve FoxPro nastavíte:

loBuilder.AddElement("parametry")
loBuilder.AddAttribute("sloupce", "rada,doklad,castka,text")
loBuilder.Pop()

Uživatel si za běhu volí sloupce, výběr se předá přes XML. Prázdný printColumns nebo prázdné XML pole = tisknou se všechny sloupce.

10. Skupiny (groups)

Skupiny seskupí řádky a zobrazí mezisoučty. Dva režimy:

Skupiny s plochou XML (groupExpression) — nejčastější

Data jsou plochá (všechny řádky na jedné úrovni), renderer seskupí podle hodnot atributů:

{
  "groups": [
    {
      "groupExpression": "rada",
      "label": "Řada {rada}",
      "headerMode": "external",
      "tableBreak": true,
      "sumExpressions": [
        { "field": "cena", "expr": "SUM(cena)", "format": "N2" }
      ],
      "sumLabel": "Celkem za řadu {rada}"
    }
  ]
}

Pozor: Data musí být setříděná podle skupinových polí! Renderer neřadí data sám — pouze detekuje změny hodnot. V FoxPro zajistěte ORDER BY v SQL dotazu.

Vlastnosti skupiny

Vizuální styl součtových řádků:

• Group subtotal (.rs) — pozadí #f0f0f0, uniformně tenké čáry 1px #ddd
• Grand total (.rt) — pozadí #e8e8e8, uniformně tlusté čáry 2px #999
• sumBorders na skupině řídí group subtotal, sumBorders na sekci řídí grand total
• U grand total: "none" a "inner-none" jsou ekvivalentní (rámec zůstává vždy)
• U group subtotal: "inner-none" odstraní i rámec (zcela neviditelné)

Více úrovní skupin

{
  "groups": [
    {
      "groupExpression": ["typ", "rada"],
      "label": "{typ} — řada {rada}",
      "headerMode": "external",
      "tableBreak": true,
      "sumExpressions": [
        { "field": "cena", "expr": "SUM(cena)", "format": "N2" }
      ]
    },
    {
      "groupExpression": "sdoklad",
      "label": "Doklad {sdoklad}",
      "headerMode": "inline",
      "tableBreak": false,
      "sumExpressions": [
        { "field": "cena", "expr": "SUM(cena)", "format": "N2" }
      ]
    }
  ]
}

Pořadí v poli = od vnější skupiny (mění se méně často) po vnitřní (mění se častěji).

Pole dostupná v záhlaví a patičce skupiny

V placeholderech {field} v label a sumLabel jsou dostupná všechna pole z datového řádku — nejen skupinové pole z groupExpression:

{
  "groupExpression": "stredisko",
  "label": "Středisko {stredisko} — {stredisko_nazev}",
  "sumLabel": "Celkem za {stredisko} — {stredisko_nazev}"
}

• label (záhlaví skupiny) — hodnoty z první věty skupiny. Libovolné pole z <row> elementu.
• sumLabel (patička skupiny) — hodnoty z poslední věty skupiny. Toto odpovídá chování FoxPro (group footer vidí poslední záznam skupiny).

11. Součty (sumExpressions)

Definují se na skupině (mezisoučty) nebo na sekci (celkový součet):

{
  "sumExpressions": [
    { "field": "cena",   "expr": "SUM(cena)",              "format": "N2" },
    { "field": "pocet",  "expr": "COUNT()",                 "format": "N0" },
    { "field": "prumer", "expr": "AVG(cena)",               "format": "N2" },
    { "field": "marze",  "expr": "SUM(prodej) - SUM(nakup)","format": "N2" },
    { "field": "jc",     "expr": "SUM(cena) / SUM(pocet)",  "format": "N2", "round": 2 }
  ],
  "sumLabel": "Celkem"
}

V sumLabel fungují placeholdery: "Celkem za řadu {rada}".

Template na sumExpression

Součtový řádek může místo prosté formátované hodnoty zobrazit šablonu s textem:

{
  "sumExpressions": [
    {
      "field": "cena",
      "expr": "SUM(cena)",
      "template": "{value:N2} {parametry.mena}"
    }
  ]
}

Výsledek: "75 020,00 EUR" místo prostého "75 020,00". Placeholdery v template:

• {value:N2} — vypočtená hodnota tohoto expr (nejjednodušší)
• {SUM(cena):N2} — agregátní výraz (lze i jiný než v expr)
• {parametry.mena} — hodnota z jiného XML elementu

11b. Víceřádkové patičky (sumRows)

Pokud potřebujete pod skupinou nebo sekcí více součtových řádků (např. celkem + splatné + po splatnosti), použijte sumRows místo sumExpressions + sumLabel:

{
  "sumRows": [
    {
      "sumLabel": "Celkem",
      "labelField": "text",
      "sumExpressions": [
        { "field": "md", "expr": "SUM(md)", "format": "N2" },
        { "field": "d", "expr": "SUM(d)", "format": "N2" }
      ]
    },
    {
      "sumLabel": "Splatné",
      "labelField": "text",
      "where": "stav=S",
      "sumBorder": "none"
    },
    {
      "sumLabel": "Po splatnosti",
      "labelField": "text",
      "where": "stav=P",
      "sumBorder": "none",
      "style": "bold",
      "hideIfZero": true
    }
  ]
}

Dědění výrazů: Druhý a třetí řádek nemá sumExpressions — automaticky použije výrazy z prvního řádku, jen je vyhodnotí jen pro řádky vyhovující podmínce where.

Pozor: sumRows a sumExpressions+sumLabel se navzájem vylučují. Pokud na skupině/sekci máte sumRows, nepoužívejte současně sumExpressions + sumLabel. Starý formát bez sumRows funguje beze změn.

11c. Vizuální stylování skupin

Barvy pozadí

Na skupině můžete nastavit barvy pozadí záhlaví a patičky:

{
  "groupExpression": "ucet",
  "headerBackground": "#ffffc0",
  "sumBackground": "#ffffff"
}

Podporované formáty barev — headerBackground, sumBackground a background na sumExpression:

• CSS pojmenované barvy: "LightYellow", "red", "darkgreen", "lightblue" atd. (case-insensitive)
• Hexa kódy: "#ffffc0", "#F00" (6-znakový nebo 3-znakový formát)
• RGB notace: "rgb(255, 255, 192)" s hodnotami 0–255
• RGBA notace: "rgba(255, 255, 192, 0.8)" — alfa kanál se používá jen v HTML

Příklady: "LightYellow", "#ffffc0", "rgb(255, 255, 192)" — všechny jsou ekvivalentní a produkují stejnou žlutou barvu.

Per-column group header

Standardně se label skupiny zobrazí jako colspan přes celou šířku. S headerLabelField se label umístí do konkrétního sloupce, headerValues přidají další hodnoty do jiných sloupců:

{
  "groupExpression": "ucet",
  "label": "{ucet:###.###} {ucty.nazev}",
  "headerLabelField": "text",
  "headerBackground": "#ffffc0",
  "headerValues": [
    { "field": "poznamka", "value": "{ucty.poznamka}", "style": "bold" }
  ]
}

Výsledek: label "067.200 Půjčka Greens Apple" se zobrazí ve sloupci text, hodnota "{ucty.poznamka}" ve sloupci poznamka. Buňky s obsahem automaticky zabírají sousední prázdné sloupce (auto-colspan).

Per-cell stylování v sum řádcích

Na sumExpression lze přidat per-cell overrides (align, background, style), nebo zobrazit neagregátní hodnotu z lookup kontextu (value místo expr):

{
  "sumExpressions": [
    { "field": "md", "expr": "SUM(md)", "format": "N2" },
    { "field": "dal", "expr": "SUM(dal)", "format": "N2" },
    { "field": "poznamka", "value": "{ucty.poznamka}", "align": "right", "background": "#c0e0ff", "style": "bold" }
  ]
}

Třetí výraz neagreguje — value zobrazí textovou hodnotu z lookup kontextu s modrým pozadím, tučným písmem a pravým zarovnáním.

11c2. Víceřádkové záhlaví tabulky (headerRows)

Property headerRows umožňuje vytvořit záhlaví ve více řádcích — typicky pro seskupení sloupců:

{
  "sections": [{
    "element": "data",
    "headerRows": [
      [
        { "text": "Identifikace", "colspan": 2, "align": "center" },
        { "text": "Hodnoty",      "colspan": 2, "align": "center", "background": "#e0f0ff" }
      ],
      [
        { "text": "Kategorie" },
        { "text": "Název" },
        { "text": "Ks",     "align": "right" },
        { "text": "Celkem", "align": "right" }
      ]
    ],
    "columns": {
      "kategorie": { "label": "Kategorie" },
      "nazev":     { "label": "Název" },
      "ks":        { "label": "Ks",     "align": "right", "format": "N0" },
      "celkem":    { "label": "Celkem", "align": "right", "format": "N0" }
    }
  }]
}

Výsledek: první řádek záhlaví zobrazí skupinové nadpisy ("Identifikace" přes 2 sloupce, "Hodnoty" přes 2 sloupce), druhý řádek zobrazí názvy jednotlivých sloupců.

Vlastnosti buňky záhlaví:

Pokud headerRows chybí, použijí se label ze columns jako jednořádkové záhlaví (zpětná kompatibilita).

11d. Podpole pod řádkem (subFields)

Pod každým datovým řádkem se mohou zobrazit doplňkové údaje — EAN, šarže, poznámka apod.:

{
  "sections": [{
    "element": "polozky",
    "columns": {
      "nazev": { "label": "Název" },
      "cena":  { "label": "Cena", "format": "N2" }
    },
    "subFields": [
      { "field": "ean", "label": "EAN" },
      { "field": "sarze", "label": "Šarže", "format": "dd.MM.yyyy" },
      { "field": "poznamka" }
    ]
  }]
}

Výstup: pod datovým řádkem se zobrazí např. EAN: 8594001234567 · Šarže: 15.01.2026 · Poznámka textu.

Auto-hiding: Pokud jsou všechna subFields pro daný řádek prázdná, podřádek se přeskočí.

11e. Mezera před grand totalem (sumSpacerMm)

Vlastnost sumSpacerMm na sekci vloží prázdný řádek o zadané výšce před grand total:

{
  "sections": [{
    "element": "data",
    "sumSpacerMm": 3,
    "sumExpressions": [
      { "field": "cena", "expr": "SUM(cena)", "format": "N2" }
    ],
    "sumLabel": "Celkem"
  }]
}

Výchozí hodnota je 0 (žádná mezera). Vizuálně oddělí poslední datový řádek od součtu.

11e. Markdown v datových buňkách

Hodnoty začínající znakem ^ se renderují jako Markdown. Bez prefixu = prostý text (beze změny).

Kde funguje

• Datová buňka — XML atribut pozn="^**důležité**" → tučný text v buňce
• Template výsledek — pokud resolvovaný template začíná ^, renderuje se jako Markdown
• SubFields — podpolová hodnota sarze="^==exp 01/2026==" → zvýrazněný text

Podporované formáty

Tip: Markdown v template

Pokud chcete formátovat buňku, která kombinuje více polí, použijte template začínající ^:

{
  "nazev_pozn": {
    "label": "Název",
    "template": "^**{nazev}**\n{poznamka}"
  }
}

Výsledek: název tučně, pod ním poznámka normálním písmem — vše v jedné buňce.

Pozor:

• Prefix ^ se automaticky odstraní — výstup neobsahuje stříšku
• V PDF se Markdown převádí na bold/italic/underline (složitější formátování se redukuje na text)
• V XLSX se Markdown tagy odstraní — zobrazí se prostý text

11f. Bloky pod tabulkou (footerRows)

Za součtovými řádky skupiny (nebo za grand totalem sekce) lze přidat bloky — popisky, hodnoty, podmíněné texty, podpisy. Typické pro inventarizační výkazy, protokoly, rekapitulace.

Typy bloků

Příklad — inventarizační výkaz

{
  "groups": [{
    "groupExpression": "ucet",
    "label": "Účet {ucet:###.###}",
    "sumExpressions": [{ "field": "castka", "expr": "SUM(castka)", "format": "N2" }],
    "footerRows": [
      { "type": "spacer", "heightMm": 3 },
      { "type": "label-value", "label": "Účetní stav:", "template": "{ucetni_stav:N2} Kč",
        "labelField": "text", "valueField": "md", "style": "bold", "fontSizePt": 10 },
      { "type": "label-value", "label": "Zjištěný stav:", "template": "{zjisteny_stav:N2} Kč",
        "labelField": "text", "valueField": "md", "fontSizePt": 10 },
      { "type": "label-value", "label": "Rozdíl:", "template": "{rozdil:N2} Kč",
        "labelField": "text", "valueField": "md", "style": "bold", "fontSizePt": 10 },
      { "type": "text", "text": "Inventarizační komise navrhuje odpis rozdílu.",
        "visibleWhen": "rozdil" },
      { "type": "signature", "signatureLeft": "Předseda komise",
        "signatureRight": "Člen komise" }
    ]
  }]
}

Vlastnosti footerRow

Priorita hodnoty

Renderer hledá hodnotu v tomto pořadí:

1. template — šablona s placeholdery: "{castka:N2} {mena}"
2. value — přímá šablona: "{ucetni_stav:N2}"
3. field + format — prosté pole s formátem

Ukotvení na sloupce

Footer rows se zobrazují mimo tabulku, ale mohou být vizuálně zarovnány ke sloupcům tabulky:

• labelField + valueField — label pod sloupcem labelField, value pod sloupcem valueField
• jen labelField — label pod sloupcem, value hned za ním
• nic — label od začátku řádku, value za ním

Na skupině vs. na sekci

• footerRows na skupině — zobrazí se po uzavření každé skupiny (za součtovými řádky)
• footerRows na sekci (top-level) — zobrazí se po grand total

{
  "sections": [{
    "element": "data",
    "groups": [{ "groupExpression": "ucet", "footerRows": [...] }],
    "footerRows": [
      { "type": "text", "text": "Celkový přehled za {header.obdobi}", "style": "title" }
    ]
  }]
}

Agregátní výrazy ve footerRows

visibleWhen a template/value ve footerRows podporují agregátní výrazy: SUM(), AVG(), MIN(), MAX(), COUNT().

{
  "footerRows": [
    { "type": "label-value", "label": "Rozdíl:", "template": "{SUM(rozdil):N2} Kč", "style": "bold" },
    { "type": "text", "text": "Stav souhlasí.", "visibleWhen": "!SUM(rozdil)" },
    { "type": "text", "text": "Komise navrhuje odpis.", "visibleWhen": "SUM(rozdil)", "style": "bold" }
  ]
}

• "visibleWhen": "SUM(rozdil)" — viditelné pokud součet rozdílů není nulový
• "visibleWhen": "!SUM(rozdil)" — viditelné pokud součet rozdílů je nulový
• "template": "{SUM(rozdil):N2}" — zobrazí vypočtený součet s formátem

Tip: Na skupině se agregáty počítají z řádků dané skupiny. Na sekci se počítají ze všech řádků sekce.

XLSX: Nový list pro každou skupinu (xlsxSheetName)

V XLSX výstupu může každá skupina vytvořit nový worksheet:

{
  "groupExpression": "ucet",
  "xlsxSheetName": "Účet {ucet:###.###}"
}

Název listu se resolvuje z dat skupiny. Neplatné znaky se automaticky odstraní (max 31 znaků). Pouze pro XLSX — HTML a PDF tuto vlastnost ignorují (tam se používá forceNewPage/tableBreak).

Tip: Pokud chcete nový list i bez šablony názvu, použijte forceNewPage: true — v XLSX se automaticky vytvoří nový list s názvem z group label.

12. Lookup tabulky

Doplní data z jiné XML tabulky (např. název firmy k číslu organizace):

{
  "groupExpression": "organizace",
  "label": "{organizace} {adresy.orgnazev:80}",
  "lookup": { "element": "adresy" }
}

Renderer dohledá v XML elementu <adresy> řádek se shodnou hodnotou organizace a zpřístupní jeho atributy.

Řetězený lookup (přes více tabulek)

{
  "lookup": [
    { "element": "hlavicky_dokladu" },
    { "element": "adresy", "key": "organizace" }
  ]
}

Krok 1: dohledá hlavičku dokladu. Krok 2: z hlavičky vezme organizace a dohledá adresu.

Přístup k lookup hodnotám

• V nadpisu skupiny: {firma}, {den:dd.MM.yyyy} — přímo jménem atributu
• V detailních sloupcích: "expr": "cena * hlavicky.kurz" — tečková notace
• V template: "template": "{cena:N2} {hlavicky.mena}" — tečková notace

Lookup na úrovni sekce (per-row)

Lookup nemusí být jen na skupině — lze ho definovat přímo na sekci. Pak se provádí per-row (pro každý řádek zvlášť):

{
  "sections": [
    {
      "element": "polozky",
      "lookup": { "element": "sklad", "key": "kod_zbozi" },
      "columns": {
        "kod_zbozi": { "label": "Kód" },
        "sklad.nazev": { "label": "Název zboží" },
        "pocet":       { "label": "Množství", "format": "N2" }
      }
    }
  ]
}

Pro každý řádek v <polozky> se dohledá odpovídající řádek v <sklad> podle kod_zbozi a zpřístupní se jeho atributy přes tečkovou notaci (sklad.nazev).

12b. Aliasy pro XML cesty (aliases)

Pokud v šabloně opakovaně používáte dlouhé tečkové cesty, můžete si definovat zkratky:

{
  "aliases": {
    "pol": "objednavka.polozky",
    "hlav": "objednavka.hlavicka"
  },
  "sections": [{
    "element": "pol",
    "columns": {
      "cena": { "label": "Cena {hlav.mena}", "format": "N2" }
    }
  }]
}

• Klíč = zkratka (alias), hodnota = plná XML cesta
• Alias se automaticky nahradí plnou cestou před renderováním
• Funguje v element, visibleWhen, template, label, expr, where a dalších místech
• Alias se nahrazuje i v tečkové notaci: {hlav.mena} → {objednavka.hlavicka.mena}

Aliasy pro lookup tabulky (více skupin na stejný element)

Typický případ: Předvaha — tři úrovně účtů (syn1, syn2, syn3), všechny hledají v jednom elementu syn_ucty. Každý alias vytvoří vlastní lookup session (cache se nestírají):

{
  "aliases": {
    "syn_ucty1": "syn_ucty",
    "syn_ucty2": "syn_ucty",
    "syn_ucty3": "syn_ucty"
  },
  "sections": [{
    "element": "data",
    "groups": [
      {
        "groupExpression": "syn1",
        "label": "{syn1} {syn_ucty1.nazev}",
        "lookup": { "element": "syn_ucty1", "key": "syn1", "foreignKey": "syn" },
        "sumLabel": "Σ {syn1} {syn_ucty1.nazev}"
      },
      {
        "groupExpression": "syn2",
        "label": "{syn2} {syn_ucty2.nazev}",
        "lookup": { "element": "syn_ucty2", "key": "syn2", "foreignKey": "syn" }
      },
      {
        "groupExpression": "syn3",
        "label": "{syn3} {syn_ucty3.nazev}",
        "lookup": { "element": "syn_ucty3", "key": "syn3", "foreignKey": "syn" }
      }
    ]
  }]
}

V XML stačí jeden element syn_ucty:

<syn_ucty>
  <row syn="0" nazev="Dlouhodobý majetek" />
  <row syn="01" nazev="Dlouhodobý nehmotný majetek" />
  <row syn="011" nazev="Zřizovací výdaje" />
</syn_ucty>

Při otevření editoru přes OpenReportEditor() se aliasy automaticky přidají do VS Code IntelliSense — nabídnou se jako syn_ucty1, syn_ucty2, syn_ucty3 s poli syn a nazev.

13. Dynamické labely sloupců

Záhlaví sloupce může obsahovat hodnotu z XML:

{
  "cena": {
    "label": "Cena {parametry.mena}",
    "format": "N2"
  }
}

Záhlaví se zobrazí jako: Cena EUR (pokud <parametry mena="EUR" />).

14. Stránkování (paged režim)

Pro sestavy s mnoha stránkami:

{
  "report": {
    "pageLayout": "paged",
    "orientation": "landscape",
    "pageMarginMm": 8
  },
  "pageHeader": {
    "left": "{company}",
    "center": "{title}",
    "right": "Strana {page} z {pages}"
  },
  "pageFooter": {
    "left": "Vytištěno: {date}",
    "right": "{filter}"
  }
}

Placeholdery v záhlaví/zápatí stránky:

Vlastnost fromPage (číslo) na pageHeader/pageFooter umožňuje zobrazit záhlaví/zápatí až od dané stránky (např. "fromPage": 2).

Tip: Přetečení stránky v tisku Pokud sestava v prohlížeči vypadá správně, ale v tisku přeteče na další stránku, je to způsobeno kumulativními odchylkami CSS renderingu (padding, border, line-height). Vlastnost pageSafetyMarginMm (výchozí 5) kompenzuje tyto odchylky. Pokud stále přetéká, zvyšte hodnotu (např. "pageSafetyMarginMm": 8). Nastavení 0 bezpečnostní okraj vypne.

15. Lokalizace (i18n)

Překlad textů v sestavě:

{
  "i18n": {
    "Celkem": "Total",
    "Strana": "Page"
  }
}

16. Průběh renderování (ShowProgress)

Při generování velkých sestav (stovky řádků) lze zobrazit dialog s průběhem a tlačítkem Storno:

loBuilder.ShowProgress = .T.
loBuilder.Render("sestava.pdf", "sablona.json")    && dialog s průběhem
loBuilder.ShowProgress = .F.                        && zpět bez dialogu

Dialog zobrazuje:

• Číslo řádku — Řádek 450 / 1 200
• Fáze PDF — řádky → formátování → uložení (počet stran)
• Storno — přeruší generování, Render() vrátí .F.

Tip: Property ShowProgress přežívá Reset() i EndBatch(). Stačí nastavit jednou a funguje pro všechna volání Render().

17. Generování z FoxPro FRX

Existující FoxPro FRX reporty lze automaticky konvertovat na JSON šablony:

*--- Auto-detekce typu (table/document) ---
loBuilder.ConvertFrxToAllFiles("C:\frx\CENIK.xml", "C:\output\")

*--- Pokud auto-detekce špatně klasifikuje typ ---
loBuilder.ConvertFrxToTableReportAllFiles("C:\frx\CENIK.xml", "C:\output\")
loBuilder.ConvertFrxToDocumentAllFiles("C:\frx\INVUCKC.xml", "C:\output\")

Výstup: 3 soubory ve výstupní složce — .json (šablona), _sample.xml (vzorová data), .prg (FoxPro kód).

Varianty jen pro JSON soubor:

loBuilder.ConvertFrxToJsonFile("CENIK.xml", "cenik.json")              && auto-detekce
loBuilder.ConvertFrxToTableReportJsonFile("CENIK.xml", "cenik.json")   && vynuceně tabulka
loBuilder.ConvertFrxToDocumentJsonFile("INVUCKC.xml", "invuckc.json")  && vynuceně dokument

Tip: Auto-detekce typu se řídí výškami bandů a počtem polí. Pokud výsledek nevypadá správně, použijte variantu s vynuceným typem (TableReport nebo Document v názvu metody).

Příklady z praxe

Jednoduchý ceník

{
  "report": {
    "title": "Ceník",
    "culture": "cs-CZ"
  },
  "header": {
    "company": "EFES spol. s r.o."
  },
  "sections": [
    {
      "element": "polozky",
      "columns": {
        "kod":    { "label": "Kód",       "align": "center", "width": "60px" },
        "nazev":  { "label": "Název" },
        "cena":   { "label": "Cena/ks",   "align": "right", "format": "N2" },
        "mj":     { "label": "MJ",        "align": "center", "width": "40px" }
      }
    }
  ]
}

Saldokonto s průběžným zůstatkem

{
  "report": {
    "title": "Saldokonto",
    "culture": "cs-CZ",
    "detailBorders": "vertical",
    "xlsxScale": 1.3
  },
  "sections": [
    {
      "element": "pohyby",
      "hideZero": true,
      "columns": {
        "faktura": { "label": "Faktura",  "suppressRepeat": true },
        "den":     { "label": "Datum",     "format": "dd.MM.yyyy" },
        "md":      { "label": "Má dáti",   "format": "N2", "align": "right", "negativeRed": true },
        "d":       { "label": "Dal",       "format": "N2", "align": "right" },
        "zust":    { "label": "Zůstatek",  "expr": "md - d", "running": true,
                     "resetAt": "organizace", "format": "N2", "align": "right" }
      },
      "groups": [
        {
          "groupExpression": "organizace",
          "label": "{organizace} {adresy.orgnazev:80}",
          "headerMode": "external",
          "tableBreak": true,
          "lookup": { "element": "adresy" },
          "sumExpressions": [
            { "field": "md",   "expr": "SUM(md)",   "format": "N2" },
            { "field": "d",    "expr": "SUM(d)",     "format": "N2" },
            { "field": "zust", "expr": "SUM(md) - SUM(d)", "format": "N2" }
          ]
        }
      ],
      "sumExpressions": [
        { "field": "md",   "expr": "SUM(md)",   "format": "N2" },
        { "field": "d",    "expr": "SUM(d)",     "format": "N2" },
        { "field": "zust", "expr": "SUM(md) - SUM(d)", "format": "N2" }
      ],
      "sumLabel": "Celkem"
    }
  ]
}

Přehled s podmíněnými sloupci (cizí měna)

{
  "sections": [
    {
      "element": "polozky",
      "columns": {
        "nazev": { "label": "Název" },
        "cena":  { "label": "Cena Kč", "format": "N2", "align": "right",
                   "visibleWhen": "!header.je_cizi_mena" },
        "cizi":  { "label": "Cena {header.mena}", "format": "N2", "align": "right",
                   "visibleWhen": "header.je_cizi_mena" },
        "kurz":  { "label": "Kurz", "format": "N3",
                   "visibleWhen": "header.je_cizi_mena" }
      }
    }
  ]
}

Hlavní kniha — pokročilé funkce sumRows

Hlavní kniha (účetní sestava) je typický příklad složitého reportu, kde potřebujete:

• součty přes nadřazenou skupinu (ne jen aktuální),
• podmíněné součtové řádky (zobrazit jen pro určitá období),
• podmíněné výpočty (aktivní účet jinak než pasivní),
• řízení stránkování z XML dat.

Sestava má typicky 3 úrovně skupin:

1. Syntetika (vnější) — seskupení účtů se stejným číslem syntetiky
2. Účet (střední) — konkrétní analytický účet
3. Období (vnitřní) — měsíce s doklady

scope — agregace přes nadřazenou skupinu

Normálně sumExpressions počítá součty přes řádky aktuální skupiny. Na vnitřní skupině (období) ale často potřebujete KZ (konečný zůstatek), který se počítá přes všechny řádky účtu — tedy přes nadřazenou skupinu.

Property "scope" na sumRow říká: "pro tento součet vezmi řádky z jiné skupiny".

{
  "groupExpression": "obdobi",
  "sumRows": [
    {
      "sumLabel": "KZ k m.{obdobi}",
      "scope": "ucet",
      "where": "obdobi<={obdobi}",
      "sumExpressions": [
        { "field": "md", "expr": "SUM(md)-SUM(d)", "format": "N2" }
      ]
    }
  ]
}

Hodnota "scope" je název groupExpression nadřazené skupiny (zde "ucet"). Renderer vezme všechny řádky dané skupiny účtu a teprve na nich aplikuje where filtr.

Dynamické where — placeholder v podmínce

Podmínka "where" na sumRow může obsahovat {field} placeholder, který se nahradí hodnotou z aktuální skupiny:

{
  "sumLabel": "PZ k m.{obdobi}",
  "scope": "ucet",
  "where": "obdobi<{obdobi}"
}

Pokud je aktuální období 2, podmínka se resolvuje na "obdobi<2" — výsledek zahrnuje jen řádky období 0 a 1. Díky tomu můžete na vnitřní skupině (období) spočítat kumulativní zůstatek k aktuálnímu měsíci.

Ternární výraz v sumExpressions

Ternární výraz umožňuje podmíněný výpočet v součtovém řádku. Syntaxe: podmínka?výraz_true:výraz_false.

{
  "sumExpressions": [
    { "field": "md", "expr": "osnova.ap=A?SUM(md)-SUM(d):0", "format": "N2" },
    { "field": "d",  "expr": "osnova.ap=P?SUM(d)-SUM(md):0", "format": "N2" }
  ]
}

Podmínka osnova.ap=A se vyhodnotí z lookup tabulky (osnova účtů). Pokud je účet aktivní (A), zobrazí se MD-D, jinak se zobrazí 0. Pro pasivní účet (P) naopak D-MD.

Ternární výrazy lze řetězit: a=1?X:a=2?Y:Z — funguje jako if-elseif-else.

SUMBY — per-subgroup agregace

Pro syntetiku (vnější skupinu), která obsahuje mix aktivních a pasivních účtů, nestačí prostý ternární výraz — ten se vyhodnotí jen jednou pro celou syntetiku. SUMBY řeší tento problém: rozparticionuje řádky podle zadaného pole a pro každou partici vyhodnotí výraz zvlášť.

{
  "sumLabel": "KZ syntetika",
  "sumExpressions": [
    { "field": "md", "expr": "SUMBY(ucet, osnova.ap=A?SUM(md)-SUM(d):0)", "format": "N2" },
    { "field": "d",  "expr": "SUMBY(ucet, osnova.ap=P?SUM(d)-SUM(md):0)", "format": "N2" }
  ]
}

SUMBY(ucet, ...) znamená: rozděl řádky syntetiky podle hodnoty ucet, pro každý účet vyhodnoť vnitřní výraz (s jeho lookup kontextem z osnovy) a výsledky sečti.

visibleWhen na sumRow

Property "visibleWhen" na součtovém řádku řídí, zda se řádek zobrazí. Podmínka se vyhodnocuje z aktuálního group elementu:

{
  "sumLabel": "Obrat m.{obdobi}",
  "visibleWhen": "obdobi>0",
  "sumExpressions": [
    { "field": "md", "expr": "SUM(md)", "format": "N2" }
  ]
}

Řádek "Obrat" se zobrazí jen pro období > 0 (ne pro počáteční zůstatky). Pro období 0 (PZ) se řádek přeskočí.

hideZero na sumExpression

Property "hideZero": true na jednotlivé sumExpression způsobí, že pokud je výsledek výrazu nula, buňka zůstane prázdná (místo zobrazení "0,00"):

{ "field": "md", "expr": "osnova.ap=A?SUM(md)-SUM(d):0", "format": "N2", "hideZero": true }

Typické použití: v Hlavní knize je KZ na straně MD jen u aktivních účtů, u pasivních je 0 — prázdná buňka je přehlednější než "0,00".

Dynamický forceNewPage a tableBreak

Vlastnosti "forceNewPage" a "tableBreak" mohou být místo true/false zadané jako placeholder, který se resolvuje z XML dat:

{
  "groupExpression": "ucet",
  "forceNewPage": "{parametr.lstrankovat}",
  "tableBreak": "{parametr.lstrankovat}"
}

FoxPro kód nastaví lstrankovat na .t. nebo .f. a renderer automaticky přepne stránkování za běhu. Hodnoty "1", ".t.", "true", "yes" se interpretují jako true, ostatní jako false.

Kompletní příklad — Hlavní kniha

{
  "renderer": "table",
  "report": {
    "title": "Hlavní kniha",
    "culture": "cs-CZ",
    "pageLayout": "paged",
    "dataFontPt": 8
  },
  "header": { "company": "Firma s.r.o." },
  "pageHeader": {
    "left": "{company}", "center": "{title}",
    "right": "Strana {page} z {pages}", "heightMm": 10, "fromPage": 2
  },
  "sections": [{
    "element": "data",
    "columns": {
      "den":    { "label": "Den",    "align": "center", "format": "dd.MM.yyyy", "width": "15.6mm" },
      "doklad": { "label": "Doklad", "template": "{rada} {doklad}", "align": "center", "width": "13.2mm" },
      "text":   { "label": "Text",   "width": "44.4mm" },
      "md":     { "label": "Má dáti","align": "right", "format": "N2", "hideZero": true, "width": "31.5mm" },
      "d":      { "label": "Dal",    "align": "right", "format": "N2", "hideZero": true, "width": "31mm" }
    },
    "groups": [
      {
        "groupExpression": "syn",
        "label": "{syn} {syn_ucty.nazev}",
        "lookup": { "element": "syn_ucty", "key": "syn" },
        "tableBreak": true,
        "headerMode": "external",
        "sumRows": [
          {
            "sumLabel": "PZ syntetika", "where": "obdobi=0",
            "sumExpressions": [
              { "field": "md", "expr": "SUM(md)", "format": "N2" },
              { "field": "d",  "expr": "SUM(d)",  "format": "N2" }
            ]
          },
          {
            "sumLabel": "Obraty syntetika", "where": "obdobi>0",
            "sumExpressions": [
              { "field": "md", "expr": "SUM(md)", "format": "N2" },
              { "field": "d",  "expr": "SUM(d)",  "format": "N2" }
            ]
          },
          {
            "sumLabel": "KZ syntetika",
            "sumExpressions": [
              { "field": "md", "expr": "SUMBY(ucet, osnova.ap=A?SUM(md)-SUM(d):0)", "format": "N2", "hideZero": true },
              { "field": "d",  "expr": "SUMBY(ucet, osnova.ap=P?SUM(d)-SUM(md):0)", "format": "N2", "hideZero": true }
            ],
            "style": "bold"
          }
        ]
      },
      {
        "groupExpression": "ucet",
        "label": "{ucet} {osnova.nazev}",
        "lookup": { "element": "osnova", "key": "ucet" },
        "forceNewPage": "{parametr.lstrankovat}",
        "tableBreak": "{parametr.lstrankovat}",
        "headerMode": "inline",
        "sumRows": [
          {
            "sumLabel": "PZ {ucet}", "where": "obdobi=0",
            "sumExpressions": [
              { "field": "md", "expr": "SUM(md)", "format": "N2" },
              { "field": "d",  "expr": "SUM(d)",  "format": "N2" }
            ]
          },
          {
            "sumLabel": "Obrat {ucet}", "where": "obdobi>0",
            "sumExpressions": [
              { "field": "md", "expr": "SUM(md)", "format": "N2" },
              { "field": "d",  "expr": "SUM(d)",  "format": "N2" }
            ]
          },
          {
            "sumLabel": "KZ {ucet}",
            "sumExpressions": [
              { "field": "md", "expr": "osnova.ap=A?SUM(md)-SUM(d):0", "format": "N2", "hideZero": true },
              { "field": "d",  "expr": "osnova.ap=P?SUM(d)-SUM(md):0", "format": "N2", "hideZero": true }
            ],
            "style": "bold"
          }
        ]
      },
      {
        "groupExpression": "obdobi",
        "hideGroupHeader": true,
        "tableBreak": false,
        "headerMode": "inline",
        "sumRows": [
          {
            "sumLabel": "PZ k m.{obdobi}",
            "scope": "ucet",
            "where": "obdobi<{obdobi}",
            "visibleWhen": "obdobi>0",
            "sumExpressions": [
              { "field": "md", "expr": "osnova.ap=A?SUM(md)-SUM(d):0", "format": "N2", "hideZero": true },
              { "field": "d",  "expr": "osnova.ap=P?SUM(d)-SUM(md):0", "format": "N2", "hideZero": true }
            ],
            "sumBorder": "none"
          },
          {
            "sumLabel": "Obrat m.{obdobi}",
            "visibleWhen": "obdobi>0",
            "sumExpressions": [
              { "field": "md", "expr": "SUM(md)", "format": "N2" },
              { "field": "d",  "expr": "SUM(d)",  "format": "N2" }
            ],
            "sumBorder": "dashed"
          },
          {
            "sumLabel": "KZ k m.{obdobi}",
            "scope": "ucet",
            "where": "obdobi<={obdobi}",
            "sumExpressions": [
              { "field": "md", "expr": "osnova.ap=A?SUM(md)-SUM(d):0", "format": "N2", "hideZero": true },
              { "field": "d",  "expr": "osnova.ap=P?SUM(d)-SUM(md):0", "format": "N2", "hideZero": true }
            ],
            "style": "bold"
          }
        ]
      }
    ],
    "sumRows": [
      {
        "sumLabel": "PZ Celkem", "where": "obdobi=0",
        "sumExpressions": [
          { "field": "md", "expr": "SUM(md)", "format": "N2" },
          { "field": "d",  "expr": "SUM(d)",  "format": "N2" }
        ]
      },
      {
        "sumLabel": "KZ celkem",
        "sumExpressions": [
          { "field": "md", "expr": "SUMBY(ucet, osnova.ap=A?SUM(md)-SUM(d):0)", "format": "N2", "hideZero": true },
          { "field": "d",  "expr": "SUMBY(ucet, osnova.ap=P?SUM(d)-SUM(md):0)", "format": "N2", "hideZero": true }
        ],
        "style": "bold"
      }
    ]
  }]
}

Tip: Lookup tabulky syn_ucty a osnova obsahují názvy syntetik a účtů. FoxPro je přidá přes AddElementWithXmlContent. Data musí být setříděná podle skupin: nejprve syn, pak ucet, pak obdobi.

Quick Wins — 10 vylepšení

Sada drobných vylepšení, která zvyšují přehlednost a použitelnost sestav. Všechna fungují ve všech třech výstupních formátech (HTML, PDF, XLSX), pokud není uvedeno jinak.

Watermark — vodoznak přes celou stránku

Vlastnost "watermark" v sekci report zobrazí velký průhledný text diagonálně přes celou stránku. Podporuje {element.field} placeholdery — pokud se placeholder resolvuje na prázdný řetězec, watermark se nezobrazí.

{
  "report": {
    "watermark": "{parametr.stav}"
  }
}

Pokud XML obsahuje <parametr stav="NÁVRH" />, zobrazí se vodoznak "NÁVRH". Pokud je atribut prázdný nebo element chybí, vodoznak se nezobrazí.

Lze zadat i statický text:

{
  "report": {
    "watermark": "KONCEPT"
  }
}

Textové modifikátory — :UPPER, :LOWER, :PROPER

Modifikátor se přidá za formát (nebo místo formátu) a změní velikost písmen ve výsledné hodnotě:

Modifikátor funguje na sloupci (format) i v template placeholderech ({pole:PROPER}):

{
  "columns": {
    "kod":   { "label": "Kód",   "format": "UPPER" },
    "nazev": { "label": "Název", "format": "PROPER" },
    "popis": { "label": "Popis", "template": "{prijmeni:UPPER} {jmeno:PROPER}" }
  }
}

Modifikátor lze kombinovat s formátem: "format": "N2:UPPER" — nejprve se aplikuje formát, pak modifikátor.

Fallback hodnoty — {pole1|pole2|'výchozí'}

Syntaxe s | (svislítkem) umožňuje zadat řetězec záložních hodnot. Použije se první neprázdná:

{
  "columns": {
    "kontakt": { "label": "Kontakt", "template": "{email|telefon|'neuvedeno'}" }
  }
}

• Pokud má řádek email, zobrazí se email.
• Pokud ne, ale má telefon, zobrazí se telefon.
• Pokud ani jedno, zobrazí se text "neuvedeno" (literál v jednoduchých uvozovkách).

Funguje i s tečkovou notací: {header.kontakt|dodavatel.email|'—'}.

Debug mód — vizuální značky chybějících polí

Vlastnost "debug": true v sekci report zapne diagnostické značky v HTML výstupu:

{
  "report": {
    "debug": true
  }
}

Pokud se placeholder {pole} nemůže resolvovat (pole v XML neexistuje), místo prázdné buňky se zobrazí červeně podbarvený text [MISSING: pole]. Pokud selže výpočet expr, zobrazí se [ERR: výraz].

Tip: Debug mód zapněte jen při vývoji šablony. V produkci by měl být vypnutý (nebo property vůbec neuvádějte).

hideColumns — vylučovací seznam sloupců

Vlastnost "hideColumns" na sekci odebere zadané sloupce z výstupu. Je to opak printColumns — místo vyjmenování viditelných sloupců vyjmenujete ty, které chcete skrýt:

{
  "sections": [{
    "element": "data",
    "hideColumns": "id, internal_code, poznamka",
    "columns": {
      "id": { "label": "ID" },
      "nazev": { "label": "Název" },
      "internal_code": { "label": "Interní kód" },
      "cena": { "label": "Cena", "format": "N2" },
      "poznamka": { "label": "Poznámka" }
    }
  }]
}

V tomto příkladu se zobrazí jen sloupce "Název" a "Cena". hideColumns se aplikuje před printColumns — můžete je kombinovat.

Zebrování řádků — alternateRowBackground

Vlastnost "alternateRowBackground" v sekci report nastaví barvu pozadí každého druhého řádku (sudé řádky):

{
  "report": {
    "alternateRowBackground": "#f9f9f9"
  }
}

Hodnota je CSS barva (hex formát). Bez této vlastnosti mají všechny řádky bílé pozadí. Doporučené světlé odstíny: "#f9f9f9" (šedá), "#f0f8ff" (modrá), "#f5fff5" (zelená).

IN operátor — test na seznam hodnot

Operátor IN funguje v podmínkách where, visibleWhen a rowStyle.when. Testuje, zda hodnota pole patří do zadaného seznamu:

{
  "sumRows": [
    {
      "sumLabel": "Aktivní celkem",
      "where": "stav IN (A, B, C)",
      "sumExpressions": [{ "field": "castka", "expr": "SUM(castka)", "format": "N2" }]
    }
  ]
}

Porovnání je case-insensitive, hodnoty se automaticky trimují. Závorky jsou povinné, hodnoty oddělte čárkami.

Příklady:

• "stav IN (A, P)" — stav je A nebo P
• "typ IN (faktura, dobropis)" — typ je faktura nebo dobropis
• "visibleWhen": "druh IN (1, 2, 3)" — zobrazit jen pro druhy 1, 2, 3

Podmíněné stylování řádků — rowStyle

Vlastnost "rowStyle" na sekci umožňuje obarvit nebo zvýraznit řádky podle podmínky. Definuje se jako pole pravidel — první pravidlo, jehož podmínka odpovídá, se aplikuje:

{
  "sections": [{
    "element": "data",
    "rowStyle": [
      { "when": "stav=STORNO", "background": "#ffe0e0", "style": "italic" },
      { "when": "castka<0",    "background": "#fff3cd", "color": "#856404" },
      { "when": "stav=A",      "color": "#006600" }
    ],
    "columns": { ... }
  }]
}

Vlastnosti pravidla:

Podmínky v when podporují všechny operátory: =, !=, >, <, >=, <=, IN(...), a také test na prázdnotu ("pole" = neprázdné, "!pole" = prázdné).

Ternární výrazy v šablonách — {podmínka?true:false}

V template sloupcích a jiných šablonách můžete použít inline podmíněný text:

{
  "columns": {
    "stav_text": { "label": "Stav", "template": "{stav=A?Aktivní:stav=P?Pasivní:Zrušený}" }
  }
}

Syntaxe: {podmínka?text_true:text_false}. Podmínky lze řetězit (else-if): {a=1?X:a=2?Y:Z}.

Ternární výrazy fungují i v sumLabel:

{
  "sumLabel": "{osnova.ap=A?Zůstatek MD:Zůstatek DAL}"
}

A v sumExpressions.expr (s agregačními funkcemi):

{
  "expr": "osnova.ap=A?SUM(md)-SUM(d):0"
}

Poznámka: V expr se ternární výraz vyhodnotí jednou pro celou skupinu. Podmínka se resolvuje z group elementu nebo lookup kontextu. Pro per-subgroup logiku použijte SUMBY.

Řešení problémů

Nic se nezobrazuje / prázdná sestava

• Zkontrolujte, že element v sekci odpovídá názvu XML elementu (názvy jsou case-sensitive)
• Zkontrolujte, že XML data opravdu obsahují potomky (<row> elementy) pod daným elementem
• Zkontrolujte, že JSON je validní — VS Code zobrazí červené podtržení u chyby

Chybí sloupec

• Klíč sloupce v columns musí přesně odpovídat názvu atributu v XML (malá/velká písmena)
• Pokud má sloupec visibleWhen, ověřte, že podmínka je splněna
• Pokud má sloupec hide: true, odstraňte tuto vlastnost

Čísla se nezarovnávají / špatný formát

• Zkontrolujte, že XML hodnota je skutečně číslo (ne text s mezerami)
• Formát "N2" potřebuje číslo s tečkou jako oddělovačem (1234.56) v XML
• Přidejte "align": "right" na sloupec s čísly

Součty se nepočítají

• sumExpressions musí být na správném místě: na skupině (mezisoučty) nebo na sekci (celkový součet)
• Pole v "expr": "SUM(cena)" musí odpovídat klíči sloupce nebo XML atributu
• Pole v "field": "cena" říká, do kterého sloupce se výsledek zapíše

JSON nejde uložit / červené podtržení

• Nejčastější chyba: čárka za poslední položkou v {} nebo []
• Chybějící uvozovky kolem textu: "label": Název → "label": "Název"
• Chybějící čárka mezi položkami: "format": "N2" "align": "right" → "format": "N2", "align": "right"
• VS Code: Ctrl+Z vrátí zpět poslední změnu

Skupiny nefungují (groupExpression)

• Data musí být setříděná podle skupinových polí (renderer pouze detekuje změny hodnot)
• groupExpression musí odpovídat názvu atributu v XML řádcích
• Pořadí skupin v poli groups = od vnější (méně časté změny) po vnitřní (častější změny)

Znakové jednotky šířek sloupců

Místo absolutních mm hodnot můžete šířky sloupců zadat relativně k fontu. Výhoda: při změně dataFontPt se šířky automaticky přepočítají — nemusíte nic měnit.

Příklad:

{
  "columns": {
    "datum":   { "label": "Datum",  "width": "d",    "format": "dd.MM.yyyy" },
    "doklad":  { "label": "Doklad", "width": "10c" },
    "castka":  { "label": "Částka", "width": "12n2", "format": "N2", "align": "right" },
    "text":    { "label": "Text",   "width": "25c" }
  }
}

Tip: Znakové jednotky fungují i v minWidth a maxWidth. Stávající mm/px/% hodnoty fungují beze změny.

Tip: CursorSchemaGenerator nyní generuje znakové jednotky automaticky ("d", "12n2", "20c" atd.).

Dávková konverze existujících JSON šablon

Pro převod stávajících mm šířek na znakové jednotky:

*--- Konverze JSON stringu ---
lcNovy = loBuilder.ConvertJsonWidthsToCharUnits(lcJson)

*--- Konverze souboru (přepíše) ---
loBuilder.ConvertJsonFileWidthsToCharUnits("C:\sablony\prehled.json")

Konverze automaticky rozpozná typ sloupce (číslo, datum, text) z formátu a zarovnání.

Doporučené šířky sloupců v mm

Pokud potřebujete ručně nastavit "width" v mm na sloupcích (místo znakových jednotek nebo auto-výpočtu), použijte tuto referenční tabulku. Šířky odpovídají vzorci z CursorSchemaGenerator:

charWidthMm = fontPt × 0.6 × 25.4 / 72
gapMm       = 2 × (0.5 − 0.015 × fontPt) × charWidthMm
paddingMm   = 2.1                           (CSS: 2×4px padding, fixed)
columnMm    = effWidth × charWidthMm + gapMm + paddingMm

Padding (2.1 mm) je CSS td{padding:2px 4px} — s border-collapse:collapse je uvnitř šířky sloupce a nezávisí na velikosti fontu. Korekce pro numerické sloupce: mezera (oddělovač tisíců) = 0.35 znaku, čárka (des. oddělovač) = 0.45 znaku.

Dostupná šířka stránky (po odečtení 2×8 mm okrajů):

Tip: CursorSchemaGenerator počítá tyto šířky automaticky. Tabulku použijte když upravujete "width" ručně v JSON šabloně a chcete, aby sloupce správně seděly na stránku.

Poznámka: Krátké textové sloupce (≤ 4 znaky) se násobí koeficientem 1.2, aby záhlaví nebylo příliš stěsnané. CursorSchemaGenerator standardně ořezává textové sloupce na maxLenString=20 znaků.

Přepočet šířek při změně velikosti písma

Tip: Pokud používáte znakové jednotky ("12c", "15n2", "d" atd.), přepočet není potřeba — šířky se přizpůsobí automaticky.

Pokud máte šířky v mm a měníte dataFontPt v JSON šabloně (např. z 8 na 7), je potřeba přepočítat šířky sloupců ("width").

Přesný vzorec (padding = fixní, content + gap = škálují se):

paddingMm = 2.1
width_nové = paddingMm + (width_staré - paddingMm) × (fontPt_nové / fontPt_staré)

Zjednodušený vzorec (chyba < 0.5 mm pro sloupce > 10 mm):

width_nové ≈ width_staré × (fontPt_nové / fontPt_staré)

Přepočítávací koeficienty (násobit stávající šířku):

Příklad přesný (8pt → 7pt, sloupec 19.0mm):

2.1 + (19.0 - 2.1) × 7/8 = 2.1 + 14.79 = 16.9mm  →  "width": "16.9mm"

Příklad zjednodušený (stejný sloupec):

19.0 × 0.875 = 16.6mm  →  "width": "16.6mm"   (rozdíl 0.3mm)

Tip: Koeficienty jsou prostý poměr fontů (fontPt_nové / fontPt_staré). Nemusíte si je pamatovat — stačí vydělit: 7/8 = 0.875, 6/8 = 0.75 atd. Přesný vzorec se vyplatí u úzkých sloupců (< 12 mm), kde fixní padding 2.1 mm tvoří velký podíl.

Pokročilé funkce sumRows (Hlavní kniha)

scope — agregace přes nadřazenou skupinu

Normálně sumRow počítá součet přes řádky aktuální skupiny. Property scope umožňuje počítat přes řádky nadřazené skupiny nebo celé sekce.

{
  "sumLabel": "KZ k m.{obdobi}",
  "scope": "ucet",
  "where": "obdobi<={obdobi}",
  "sumExpressions": [
    { "field": "md", "expr": "osnova.ap=A?SUM(md)-SUM(d):0", "format": "N2", "hideZero": true }
  ]
}

Typický případ: Skupina obdobi (měsíce) je vnořená v skupině ucet. KZ k měsíci potřebuje sčítat přes všechny řádky účtu, ne jen aktuální měsíc. "scope": "ucet" expanduje rozsah agregace na celou nadřazenou skupinu.

Dynamické where s placeholdery

Where podmínka může obsahovat {field} — hodnota se dosadí z aktuální grupy:

• "where": "obdobi<{obdobi}" — při období=3 → "obdobi<3"
• "where": "obdobi<={obdobi}" — při období=3 → "obdobi<=3"

Ternární výraz v sumExpression

Podmíněný výpočet: "expr": "podmínka?true_výraz:false_výraz"

{ "field": "md", "expr": "osnova.ap=A?SUM(md)-SUM(d):0", "format": "N2" }

Pokud účet je Aktivní (osnova.ap=A), spočítá MD−Dal. Jinak vrátí 0. Podmínka využívá lookup kontext (osnova.ap se dohledá z lookup tabulky).

SUMBY — per-subgroup agregace

Pro situace kde účty pod jednou syntetikou mají různé strany (A/P):

{ "field": "md", "expr": "SUMBY(ucet, osnova.ap=A?SUM(md)-SUM(d):0)", "hideZero": true }

SUMBY rozdělí řádky podle ucet, pro každý účet vyhodnotí ternární výraz (s jeho vlastním lookup kontextem) a sečte výsledky. Typicky pro SYN=343 (DPH) kde 3431 je Aktivní a 3432 je Pasivní.

visibleWhen na sumRow

Řádek se zobrazí jen při splnění podmínky:

{ "sumLabel": "PZ k m.{obdobi}", "visibleWhen": "obdobi>0" }

Řádek "Počáteční zůstatek k měsíci" se nezobrazí pro období 0 (samotný PZ).

hideZero na sumExpression

Per-buňka blank if zero — buňka zůstane prázdná pokud výsledek je 0:

{ "field": "md", "expr": "osnova.ap=A?SUM(md)-SUM(d):0", "hideZero": true }

Rozdíl: hideIfZero na sumRow skryje celý řádek. hideZero na sumExpression skryje jen jednu buňku.

Dynamický forceNewPage / tableBreak

forceNewPage a tableBreak mohou být řízeny z XML dat:

{
  "groupExpression": "ucet",
  "forceNewPage": "{parametr.lstrankovat}",
  "tableBreak": "{parametr.lstrankovat}"
}

Hodnota "1" nebo "true" → zapnuto, ostatní → vypnuto.

Quick Wins — 10 vylepšení

Watermark

Text přes celou stránku (vodoznak):

{ "report": { "watermark": "NÁVRH" } }

Podporuje {field} placeholdery: "watermark": "{header.stav}". Prázdný řetězec = nezobrazit.

Textové modifikátory (:UPPER, :LOWER, :PROPER)

Transformace textu ve formátu nebo šabloně:

{
  "label": "Firma",
  "format": "UPPER"
}

V šablonách: {firma:UPPER}, {nazev:PROPER}. Kombinace s formátem: {castka:N2:UPPER}.

Fallback hodnoty (coalesce)

První neprázdná hodnota z více polí:

{ "template": "{nazev_cz|nazev_en|'Bez názvu'}" }

Znak | odděluje alternativy. Literál v uvozovkách 'text' slouží jako poslední fallback.

Debug mód

Pro ladění šablon — zobrazí chybové markery místo tichého ignorování:

{ "report": { "debug": true } }

V HTML: [MISSING: pole] (žlutý) a [ERR: výraz] (červený).

hideColumns — vylučovací seznam

Opak printColumns — které sloupce NEUKÁZAT:

{ "sections": [{ "hideColumns": ["id", "internal_code"] }] }

Sloupce zůstávají dostupné pro výpočty a lookup, jen se nezobrazí.

Zebrování řádků (alternateRowBackground)

Střídavé podbarvení sudých řádků:

{ "report": { "alternateRowBackground": "#f9f9f9" } }

IN operátor

Testování příslušnosti k množině ve where, visibleWhen, rowStyle:

{ "where": "typ IN (P, V, S)" }

Podmíněné stylování řádků (rowStyles)

Barva pozadí, tučné písmo nebo barva textu podle podmínky:

{
  "rowStyles": [
    { "when": "stav=STORNO", "background": "#ffe0e0", "style": "bold", "color": "red" },
    { "when": "castka<0", "background": "#fff3e0" }
  ]
}

První matchující pravidlo se aplikuje na řádek.

Ternární výrazy v šablonách

Inline podmíněný text v libovolné šabloně:

{
  "template": "{stav=A?Aktivní:Neaktivní}",
  "label": "Účet {ucet} {osnova.ap=A?AKTIVNÍ:PASIVNÍ}"
}

Syntaxe: {podmínka?text_true:text_false}. Podmínky: =, !=, >, <, IN, field, !field.

Časté úpravy — rychlý přehled

Příklad: Jak přidat nový sloupec

V sekci columns přidejte nový klíč (= název XML atributu) s nastavením:

"columns": {
  "kod":    { "label": "Kód",  "align": "center", "width": "60px" },
  "nazev":  { "label": "Název" },
  "poznamka": { "label": "Poznámka" }
}

Příklad: Jak přidat součet

Na sekci nebo skupinu přidejte sumExpressions:

"sumExpressions": [
  { "field": "cena", "expr": "SUM(cena)", "format": "N2" }
],
"sumLabel": "Celkem"